IconIDToRgn

IconIDToRgn
Header:	Icons.h		Carbon status:	Supported

Converts the icon mask in an icon family to a region.

OSErr IconIDToRgn (
     theRgn, 
    const Rect *iconRect, 
    IconAlignmentType align, 
    SInt16 iconID
);

theRgn

On return, a handle to the requested region. You must allocate memory for the region handle before calling this function.

The returned region corresponds to the icon’s mask (the mask defined by either an 'ICN#' or 'ics#' resource in an icon family, according to the rectangle and alignment specified in the iconRect and align parameters).

Once you have a region that describes the icon mask for a given icon, you can use it to perform accurate hit-testing and outline dragging of the icon in your application.

iconRect

A pointer to the rectangle in which to draw the icon, specified in local coordinates of the current graphics port. The function uses this rectangle as the bounding box of the region. The function determines, from the size of the rectangle specified here, which icon mask to use from the specified icon family.

align

Specifies how the function should align the mask within the rectangle. See “Alignment Type Values” for a description of the values you can use in this parameter.

iconID

The resource ID of the icon for which to create a region. In general, you should specify your icon resources as purgeable.

function result: A result code.

SPECIAL CONSIDERATIONS

This function may move or purge memory blocks in the application heap. For that reason, your application should not call it at interrupt time.

AVAILABILITY

Supported in Carbon. Available in CarbonLib 1.0 and later when InterfaceLib 7.1 or later is installed. Exported by CarbonLib 1.0 and later and by InterfaceLib 7.1 and later.